home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / TSR / TPPOP18C / POPUP.DOC < prev    next >
Text File  |  1989-01-22  |  14KB  |  388 lines
  1.  
  2.                           T U R B O    P O P
  3.  
  4.              Memory Resident PopUp Routines Version 1.8c
  5.                      for Turbo Pascal Version 5.0
  6.  
  7.                           Copyright (c)1988
  8.                        Ross Neilson Wentworth
  9.  
  10.                 Custom software at reasonable prices!
  11.  
  12.                   THIS PACKAGE IS NOT PUBLIC DOMAIN
  13.  
  14.                           All Rights Reserved
  15.  
  16.  
  17.                               DISCLAIMER
  18.  
  19.                     This software is provided without
  20.                      warranty, expressed or implied.
  21.  
  22.  
  23. The Turbo Pascal Units contained in this package will enable you to
  24. quickly and easily create popup programs.  Also included is a very simple
  25. windowing package.
  26.  
  27. All source code is included so that you may modify it to your hearts
  28. desire.  Do NOT release modified versions of this package under any
  29. circumstances.
  30.  
  31. Turbo Pascal Version 5.0 is required to use this package.  TASM 1.0
  32. or MASM 5.1 is required to to re-assemble the low-level modules.
  33.  
  34. If you find this code useful, please send $20 to the address below or
  35. make a $20 donation to the "The Historic Oaks Foundation", located in
  36. Agoura Hills and Novato, California.  Let me know if you make the
  37. donation and you will receive full credit for registration (receipt or
  38. copy of cancelled check required).
  39.  
  40. If you use this code in any commerical program this payment is required.
  41. Shareware is considered commercial upon receipt of first registration.
  42.  
  43.                    Ross Neilson Wentworth
  44.                    Serendipity Software
  45.                    1422 Elkgrove Circle, #3
  46.                    Venice, CA  90291
  47.                    (213)399-1244
  48.  
  49.  
  50. Features of This Package
  51. ========================
  52.  
  53.   o Easily create memory resident popup programs (SideKick-like).
  54.   o Automatic program detection to prevent multiple loading.
  55.   o Allows TSR's with conflicting hot-keys
  56.   o Simple program removal
  57.   o Uses proven TSR techniques.
  58.   o All DOS functions allowed from within resident program (except
  59.     I/O redirection), you can safely access the disk!
  60.   o No load-order limitations (except those imposed by other TSR's).
  61.   o Low code overhead, slightly over 1k EXE size increase to standard
  62.     application.
  63.  
  64. One of the problems with writing popup programs is DOS is not reentrant.
  65. That is, if you popup while DOS is busy you are very likely to crash the
  66. system.  This package does all the necessary checking and will only popup
  67. when it is safe.  This allows your program to do virtually anything including
  68. file access.  The one limitation is that it can not allocate additional memory.
  69. You can still use heap memory, just don't use the DOS function to allocate or
  70. modify a current memory block.
  71.  
  72. To guarantee a safe pop-up program it is necessary to grab hold of several
  73. interrupt vectors.  When the program is first initialized the following
  74. vectors are intercepted:
  75.  
  76.      08h      timer
  77.      09h      keyboard
  78.      13h      disk i/o
  79.      28h      backprocess
  80.      2Fh      multiplex
  81.  
  82. When the program is popped up, two additional vectors are also intercepted:
  83.  
  84.      23h      control-break
  85.      24h      critical error
  86.  
  87. In addition, a couple of other internal values are changed while the
  88. program is active:
  89.  
  90.      The Disk-Transfer-Area is saved and the popup's installed
  91.      The BREAK status is saved then turned off
  92.  
  93. These four items are restored when the TSR relinquishes control.
  94.  
  95. A sample program is provided that shows how to implement a popup program.
  96.  
  97. ===============================================================================
  98. Contents of POPUP:
  99.  
  100.   Function Installed(OurID : Byte) : Byte;
  101.  
  102.     Given a unique program ID number, this function returns zero (0) if
  103.     the program has not already been installed.  A nonzero value indicates
  104.     it has already been installed or an error has occured:
  105.  
  106.        1 : PRINT.COM detected.  Under DOS 2.x, the TSR must be loaded
  107.            before PRINT.COM.
  108.        2 : The program is already installed.
  109.        3 : Internal error, can't install.
  110.  
  111.     Error 3 is usually caused by a poorly designed TSR program that has
  112.     already been loaded into memory.  Try loading your program before any
  113.     others.  Experimenting with the order of loading should point out the
  114.     bad TSR.
  115.  
  116.   Procedure StayResident(OurID : Byte;ProgramAdress : Pointer;HotKey: Word);
  117.  
  118.     HOTKEY is your key combination that will activate your program.  It is of
  119.     type WORD where the low byte is the scan code and the high byte is the
  120.     shift status (ALT, CTRL, SHIFT, etc.  See below).  ProgramAddress is a
  121.     pointer to your popup procedure that you want called.  Precede the
  122.     program name with an '@' to pass a pointer.
  123.  
  124.          StayResident($69,@NotePad,Alt+LeftShift + $20);  (ALT-LeftShift-D);
  125.  
  126.     The shift status values are documented below.
  127.  
  128.     OurID is a unique number for your resident program.  Each different
  129.     TSR that you write should have a different ID number.  For maximum
  130.     compatibility, you should allow the user to change the ID number,
  131.     perhaps by using a 'command-line' option, i.e. /I=155.  MS-DOS reserves
  132.     ID numbers 0 to 80h for internal use.
  133.  
  134.   Procedure ReleaseBlock(Segment : Word);
  135.  
  136.     This inline macro releases the block of memory given a segment number.
  137.  
  138.   Procedure ReleaseEnvironment;
  139.  
  140.     Releases the block of memory holding the program's environment.  It keeps
  141.     track of whether it has already been called so that multiple calls will
  142.     not be harmful.
  143.  
  144. ===============================================================================
  145. Contents of UNHOOK:
  146.  
  147.   Function Installed(MultID : Byte) : Boolean;
  148.  
  149.     Returns TRUE if the resident program is in memory.
  150.  
  151.   Function OKToUnload(MultID : Byte) : Boolean;
  152.  
  153.     Returns TRUE if it is safe to unload the resident program from memory.
  154.  
  155.   Procedure RemoveProgram(MultID : Byte);
  156.  
  157.     Releases the memory and restores the interrupt vectors used by the
  158.     resident program.
  159.  
  160. ===============================================================================
  161. Contents of WINDOWS:
  162.  
  163.   Procedure MakeWindow(X1,Y1,X2,Y2,Foreground,Background : Word;Border : BorderType);
  164.  
  165.    This procedure saves the current screen memory and creates a bordered
  166.    window.  X1, Y1, X2, and Y2 are the same values used by Turbo's WINDOW
  167.    procedure.  Foreground and Background are the color attributes of the
  168.    window.  Border is the type of border desired.  Possible border types
  169.    are:
  170.  
  171.           NONE          -   no border
  172.           SINGLE        -   single line
  173.           DOUBLE        -   double line
  174.           DOUBLETOP     -   double top lines, single side lines
  175.           DOUBLESIDE    -   double side lines, single top lines
  176.           SOLID         -   solid block (space character)
  177.  
  178.     Example useage:
  179.  
  180.             MakeWindow(5,5,30,10,Black,White,Double);
  181.  
  182.   Procedure DrawBox(X1,Y1,X2,Y2,Forground,Background : Word;Border : BorderType);
  183.  
  184.     Works just like MakeWindow but doesn't save the underlying screen and
  185.     doesn't use a matching RemoveWindow.
  186.  
  187.   Procedure RemoveWindow;
  188.  
  189.     Removes the current top window, does nothing if there isn't any windows
  190.     defined with the MakeWindow procedure.
  191.  
  192.   Procedure SetCursor(Cursor : Word);
  193.  
  194.     Sets the cursor shape.  Some software packages turn off the cursor
  195.     so this is provided so you can set your prefered cursor shape.  The
  196.     windowing package saves the cursor shape of the underlying screen so
  197.     there is no need to restore it.
  198.  
  199.   Var VideoMode : Word;
  200.  
  201.     A DOS variable that holds the current video mode.  Use this to test
  202.     for and avoid activating in graphics modes.
  203.  
  204. ===============================================================================
  205. SAMPLE PROGRAMS
  206. ===============
  207.  
  208. POPDICE is a fully functional sample pop-up program.  After loading, pressing
  209. ALT-LeftShift-D will pop-up a fancy dice rolling program designed for war
  210. games and roll-playing games.
  211.  
  212. NODICE will remove POPDICE from memory if it is safe to do safe.  Alternately,
  213. a second program, REMOVE, can be used to unload ANY resident program written
  214. with this package.  REMOVE accepts a single I.D. number on the command line.
  215. This is the same as the program's signature.
  216.  
  217. ===============================================================================
  218.  
  219. Caveats
  220. =======
  221.  
  222. You MUST handle all possible errors.  If at any time the program halts
  223. due to a runtime, I/O, or critical error the system will probably crash.
  224. Before the resident program is entered, POPUP.TPU's critical error handle
  225. is restored so that you can query IOResult for errors.
  226.  
  227. Use the $M directive to reduce memory requirements.  Make a high guess of
  228. memory requirements for your program then double or triple it.  Compile
  229. and run the program to make sure it runs. If it doesn't increase memory.
  230. If it does run decrease it.  Keep decreasing the memory until the program
  231. crashes then increase memory and add a little extra for slop.
  232.  
  233. You should test the video mode when your routine is first run.  The windows
  234. unit can not properly save graphics screens so you might want to beep and
  235. exit.  You could, of course, write your own windowing package that can save
  236. graphics screens.  This could be a problem with some of the new video modes
  237. that have tremendous memory requirements.
  238.  
  239. Shift Keys
  240. ==========
  241.  
  242. RightShift  $01
  243. LeftShift   $02
  244. Control     $04
  245. ALT         $08
  246.  
  247. ScrollLock  $10   { these four are not supported in this version }
  248. NumLock     $20   {  "     "     "     "     "     "     "     " }
  249. CapLock     $40   {  "     "     "     "     "     "     "     " }
  250. Insert      $80   {  "     "     "     "     "     "     "     " }
  251.  
  252. The shift status values are defined in the interface portion of the PopUp
  253. unit.  The values are already shifted to the left 8 bits to save you the
  254. trouble.  Simple add the different shift keys you want to the scan code
  255. and pass that value to StayResident.  For example, for a program to popup
  256. when both shift keys are pressed as well as the period you would issue
  257. the command:
  258.  
  259.           StayResident(@MyPopUp,RightShift + LeftShift + $34);
  260.  
  261. The coding of the popup routines makes undefined keys possible, thus
  262. reducing the chance of keyboard confict.  For example the numeric pad
  263. '5' (the center key) is undefined for most combinations.  This allows
  264. you to use combinations such as (Control + LeftShift + $4C) with a
  265. high degree of certainty that it won't conflict with other programs.
  266.  
  267. Keyboard Scan Codes
  268. ===================
  269.  
  270. 0  $0B     6  $07     C  $2E     I  $17     O  $18     U  $16
  271. 1  $02     7  $08     D  $20     J  $24     P  $19     V  $2F
  272. 2  $03     8  $09     E  $12     K  $25     Q  $10     W  $11
  273. 3  $04     9  $0A     F  $21     L  $26     R  $13     X  $2D
  274. 4  $05     A  $1E     G  $22     M  $32     S  $1F     Y  $15
  275. 5  $06     B  $30     H  $23     N  $31     T  $14     Z  $2C
  276.  
  277. BS   $0E
  278. CTL  $1D
  279. ESC  $01
  280. TAB  $0F
  281. RET  $1C
  282.  
  283. -  $0C     `  $29
  284. =  $0D     \  $2B
  285. [  $1A     ,  $33
  286. ]  $1B     .  $34
  287. ;  $27     /  $35
  288. '  $28
  289.  
  290. LeftShift   $2A
  291. RightShift  $36
  292. ALT         $38
  293. Space       $39
  294. CapLock     $3A
  295.  
  296. F1  $3B     F2  $3C     F3  $3D     F4  $3E     F5   $3F
  297. F6  $40     F7  $41     F8  $42     F9  $43     F10  $44
  298.  
  299. NumLock     $45       ScrollLock  $46       Home        $47
  300. UpArrow     $48       PageUp      $49       grey -      $4A
  301. RightArrow  $4B       Center      $4C       LeftArrow   $4D
  302. grey +      $4E       End         $4F       DownArrow   $50
  303. PageDown    $51       Ins         $52       Del         $53
  304.  
  305. ==============================================================================
  306. Version History
  307.  
  308. 1.8c 22 January 1989
  309.  
  310.      Minor bug in the window package was corrected that would cause
  311.      window types of NONE not to be set properly.
  312.  
  313. 1.8b 30 December 1988
  314.  
  315.      Faster box drawing in the WINDOWS unit by using assembler routine.
  316.      When archive was updated several necessary files were inadvertantly
  317.      left out.
  318.  
  319. 1.8  3 November 1988
  320.  
  321.      Improved detection of unsafe unload conditions.  Minor bug fixed
  322.      on saving and restoring the cursor shape.  Made changes to source
  323.      so that it will assemble using Turbo Assembler.
  324.  
  325. 1.7  16 October 1988
  326.  
  327.      Removed the READKEY procedure.  Instead, interrupt 16h is grabbed
  328.      to prevent resident program lock-outs.  Changed to using interrupt
  329.      08h instead of 1Ch.  For some reason, using the later with some
  330.      programs would cause the system to lock up.
  331.  
  332. 1.6  1 October 1988
  333.  
  334.      Added experimental unload procedure.  Minor cosmetic changes.
  335.      Improved support for conflicting hot-keys.  Removed RestoreVectors
  336.      and placed in a separate unit.
  337.  
  338. 1.5  20 September 1988
  339.  
  340.      Code added to detect programs that have already been loaded, thus
  341.      preventing multiple loading of the same TSR.  Minor bug fix.
  342.      Documentation corrections.
  343.  
  344. 1.4  31 August 1988
  345.  
  346.      All source code now included in the archive.  Removed the FREE unit
  347.      due to problems.  Use Mark/Release instead.
  348.  
  349. 1.2  21 March 1988
  350.  
  351.      Minor correction in the low-level popup code - not all of the
  352.      registers were being saved.
  353.  
  354. 1.1  13 March 1988
  355.  
  356.      Changed popup code so the user procedure is declared as FAR rather
  357.      than as INTERRUPT.
  358.  
  359. 1.0  Ported from Turbo Pascal 3.0, changed name, and restarted version
  360.      number.
  361.  
  362. Previously:  Used a lot of INLINE code under Turbo Pascal 3.x.
  363.  
  364. REFERENCES
  365. ==========
  366.  
  367. Advanced MS-DOS, Ray Duncan, Microsoft Press
  368.  
  369. The MS-DOS Encyclopedia, Microsoft Press
  370.  
  371. Magazine articles too numerous to list.
  372.  
  373. Tidbits of knowledge gained from the Fido/Opus Network.
  374.  
  375. ACKNOWLEDGEMENTS
  376. ================
  377.  
  378. I wish to thank the many programmers who pioneered the development of
  379. Terminate-and-Stay-Resident programs, on whom's shoulders I am standing.
  380.  
  381. ===============================================================================
  382.  
  383. Legal Stuff
  384. ===========
  385.  
  386. Sidekick, Turbo Assembler, and Turbo Pascal are Trademarks or Registered
  387. Trademarks of Borland International, Inc.
  388.